Microsoft's Messaging Application Programming Interface (MAPI) is a set of high level DLL functions that are the foundation of electronic mail in Windows. Applications use these functions to create, manipulate, transfer, and store messages.
The scripts and examples in this book demonstrate how to access MAPI from ToolBook, but are not intended to teach you MAPI. It is assumed that you are familiar with and have documentation for MAPI.
The handlers which directly access the MAPI functions are all found in the script of this book.s which applications used to create, manipulate, transfer, and store messages. Most of these functions are exported from MAPI.DLL and form the basis for electronic mail in Windows.
The scripts and examples in this book demonstrate how to access MAPI from ToolBook, but are not intended to teach MAPI to the user. In fact. it is assumed that user is familiar with and has documentation for MAPI.
The handlers which directly access the MAPI functions are all found in the book script.
Sending Messages
Sending Messages
Sending Messages5
The example below illustrates how to send a message without using the MAPI dialog box. Fill in the fields below and click the button when you are ready to send the message..the message.
Send Message
.'+ +F
.'+ +F
}str_sent
getAddress
sendMessage
s_MAPIError
str_notSent
buttonClick
buttonClick
4s_MAPIError
there
no recipient supplied
-- call up
6 Address Book
getAddress()
--
we don't
address we won't
a message
-- fill
appropriate
sendMessage(
"sub",
"body")
-- confirm whether
was sent
str_notSent()&&
str_sent()
&Send Message
Bob N.
We're almost there now.
Don't blow it!
Subject:
Text:
Submit Reports
Receive Reports
Receive Reports
View New
uupdateMessages
buttonClick
buttonClick
-- scan incoming mail
problem reports
setup the
-- (
message
handled
updateMessages
&View New
delete
[4deleteMessage
uupdateMessages
str_OK
s_MsgHandles
s_MsgNum
s_MAPIError
Rstr_notDelete
buttonClick
buttonClick
4s_MsgNum,s_MsgHandles,s_MAPIError
-- delete the current message
deleteMessage(
<> str_OK()
str_notDelete()&&
-- refresh
[ list
-- (
handled
updateMessages
D&elete
Previous
8parseMsgText
s_MsgNum
buttonClick
buttonClick
4s_MsgNum
mail message
disable
G = 1
enabled
B"Next" =
-- fill
~fields
-- (
handled
parseMsgText
&Previous
Previous
8parseMsgText
s_MsgCount
s_MsgNum
buttonClick
buttonClick
4s_MsgNum,s_MsgCount
tmessage
, disable
enabled
B"Previous" =
-- fill
fields
-- (
handled
parseMsgText
&Next
Submit Reports
Submit Reports
buttonClick
buttonClick
"Submit Reports"
&Submit Reports
examples
buttonClick
buttonClick
the example
Fclose
isOpen
"examples"
&Done
toLabel
From:ss:
problem
Department
address
msgnum
No messagesf 10
toLabel
Department:
office
phone
toLabel
Problem Area:
toLabel
Phone::::::::
toLabel
Office: Area:
toLabel
Description of problem:
description
toLabel
Sent:ss:
timestamp
Example: Problem Reports
*ClassTbl*
*ClassEntry*
*PTABLE*
*WINDOWSEG*
Viewer
*ICONRESTAB*
*ICONRESSEG*
*ICONRES*
Background
*OBJTABLE*
*IDTABLE*
*NAMETAB*
Rectangle
Ellipse
RoundedRectangle
Polygon
IrregularPolygon
AngledLine
Curve
Field
RecordField
ComboBox
Button
PaintObject
Picture
Hotword
*RHOTWORD*
Group
Stage
*TbxBase*
functions
MAPIFindNext(
, 0, 0,
--
Verifying Names
-- a notify handler was used
the address
you enter
Verifying Names
Verifying Names
Click Check Names to get the full names of those displayed in the upper field and place them in the lower field.
If a name is ambiguous, MAPI displays a dialog box that allows the user to choose the correct name.opriate... field.
If a name is ambiguous, MAPI will display a dialog allowing the user to choose which name is appropriate.
Check Names
1, #>
checkNames
partial
s_MAPIError
str_notResolved
buttonClick
buttonClick
4s_MAPIError
a list
verified names
checkNames(
"partial")
error condition
"full" =
--
some
hcould
xbe resolved:
-- the
value
--
those that
--
--
,were
str_notResolved()&
&Check Names
partial
Tom,Dick,Harry
enterPage
notifybefore
= "Tom,Dick,Harry"
Tom,Dick,Harryelda
enterPage
notifybefore
enterPage
examples
Linking to MAPI.DLL
Sending Messages
Checking For Unread Mail
-- notify handlers were used
[the fields
-- you enter
Checking For Unread Mail
Checking For Unread Mail
The script of this button steps through the messages in your incoming mail folder, looking for unread messages. The sender and subject of each unread message are placed in the fields below.. fields.
The functions for handling messages in Windows are exported from MAPI.DLL. Click View DLL Functions to see the way these functions are prototyped in OpenScript.ped in OpenScript.
buttonClick
buttonClick
display a
which
-- linking information
&View DLL Functions
Composing Mail
Composing Mail
Composing Mail
Click Compose Message to open the MAPI dialog box you use to compose and send a message.
Click Attach a File if you want to attach a file to the message you compose.....se buttons bring up the MAPI dialog box allowing you to compose and send a message.
The second button attaches a file to the message that you compose.
Compose Message
s_MAPIError
ucomposeMessage
buttonClick
buttonClick
4s_MAPIError
-- compose a message
composeMessage()
returned -
error condition
k <>
&Compose Message
Attach a File
filename
ZsendFile
s_MAPIerror
buttonClick
buttonClick
4s_MAPIerror
-- compose a message
attached file
sendFile(
"filename")
returned -
b condition
s_MAPIError <>
&Attach a File
filename
enterPage
notifyBefore
C:\JX\MAPI\MAPI.TBKKKKKKKBK
enterPage
Composing Mail
Looking up Addresses
Verifying Names
Counting Messages
Counting Messages
Counting Messages
Click the appropriate button below to count the messages in your incoming mail folder.by stepping through them one at a time.il folder by stepping through them one at a time. This first counts all messages, and the seconds counts only unread messages.
Count All Messages
.'+ +F
.'+ +F
FALSE
str_msgCountAll
l'getNextMsgID
1RgetFirstMsgID
buttonClick
buttonClick
ZLONG count
the ID
message (read
unread)
getFirstMsgID(FALSE)
found
--
getNextMsgID(
str_msgCountAll(
Count &All Messages
Count Unread Messages
.'+ +F
.'+ +F
l'getNextMsgID
Dstr_msgCountUnread
1RgetFirstMsgID
buttonClick
buttonClick
ZLONG count
the ID
message (read
unread)
getFirstMsgID(TRUE)
found
--
getNextMsgID(
str_msgCountUnread(
Count &Unread Messages
message
str_of
Problem Report
str_problemRep
Aborting operation: Me
Arial
Arial
Arial
Arial
Sans Serif
Arial
Arial
MS Sans Serif
ge id 23
examples
Page "Submit Reports"
MAPI Tutorial
Page "functions"
examples
Submit Reports
department
Salestingnt
Development
Executive
Finance
Marketing
Sales
Technical Support
Testings
problem
Hardware Problemtion
E-Mail
Hardware Installation
Hardware Problem
Network
Other
Phones
Printers
Software Installation
Software Problem
office
phone
x3434
description
My machine won't boot right. The disk keeps running and running but nothing happens.
Change Address
nameList
getAddress
buttonClick
buttonClick
-- call up the Addressbook dialog
a list
names
nameList = getAddress()
namelist
&Change Address
Receive Reports
Receive Reports
buttonClick
buttonClick
"Receive Reports"
ceive Reports
examples
buttonClick
buttonClick
the example
Fclose
isOpen
"examples"
&Done
Jim Geldmacher
str_problemRep
enterPage
subject
standard
reports
notifybefore
= str_problemRep()
Problem Report
toLabel
Address:
toLabel
Subject:
toLabel
Department:
toLabel
Problem Area:
toLabel
Phone::::::::
toLabel
Office: Area:
toLabel
Description of problem:
Submit Report
Office:
Department:
phone
description
problem
Problem Report
Phone:
Description:
Problem:
sendMessage
nstr_notSubmit
s_MAPIError
office
department
str_submit
buttonClick
buttonClick
4s_MAPIError
ZmsgTxt
-- build the
message
' = "Problem Report"
D = "Department:"
combobox "department"
3problem"
= "Office:"
"office"
= "Phone:"
"phone"
= "Description:"
"description"
sendMessage(
"sub",
str_notSubmit()&&
str_submit()
bmit Report
enterPage
&Submit Report
&Receive Reports
~HVHVH
1993,1994. Asymetrix Corporation. All Rights Reserved.
"Attacment Not Found" --MAPI_E_ATTACHMENT_NOT_FOUND
"Failure Opening Attachment" --
LOPEN_FAILURE
?Writing
|WRITE_FAILURE
"Unknown
+" --MAPI_E_UNKNOWN_RECIPIENT
"Bad
," --MAPI_E_BAD_RECIPTYPE
"No Messages"
--MAPI_E_NO_MESSAGES
"Invalid
;" --MAPI_E_INVALID_MESSAGE
Large" --MAPI_E_TEXT_TOO_LARGE
M/" --MAPI_E_INVALID_SESSION
Supported" --MAPI_E_TYPE_NOT_SUPPORTED
"Ambiguous
-" --MAPI_E_AMBIGUOUS_RECIPIENT
g(:"&&
;+a filename
/has been stripped
path information
fName
harCnt, i
charCnt =
- 1)
Vi+1
)) allocates a block
global
* nSize
ZhMem,ptr
ma_globalAlloc(66,
%) -- 66
Movable, Zero-Init
str_noMem()
ma_globalLock(
)() frees
)lpPointer
ma_Globalhandle(
bitAnd 0x0000FFFF
+selector.
ma_GlobalUnLock(
retValue = ma_GlobalFree(
2() establishes a
2DLL
-- a
p' indicating
found.
sysS =
provide messaging
X"mapi.dll"
1, STRING,
I1, \
<2 MAPIDeleteMail (
.links
kernel
$ managment
INT ma_globalUnlock=
%=globalFree(
H3 ma_globalHandle=
tbkwin
k5 "tb40win.
ma_getWinIniVar=
5 disconnects
str_noUnread
str_msgCountAll
str_msgCountUnread
!6"&&
J7
I."&&\
e6Microsoft
7-compatible e-
3 client software installed"&&\
7 correctly."
I."&&\
F,"&&\
9wish
str_notResolved
"These
str_sent
str_notSent
str_notSubmit
"Report
xsubmitted:"
str_submit
str_notDelete
xdeleted:"
str_noMessages
str_error
str_update
"Update
str_cancel
"Cancel"
str_message
str_of
str_problemRep
"Problem
"Aborting operation:
Allocation
buttonClick
ZnameText,subText,scrollText
ZLONG msgNum
the ID
unread message
getFirstMsgID(TRUE)
-- repeat
Zno more messages are found
-- optimization:
faster
aincremental
Fplace
, than
Qdirectly
. In
list
generated one
Fplaced
fields
complete.
-- extract
sender
= getMsgName(
--
subject
= getMsgSub(
--
places dummy
(only
--
shows on th
--
technique allows you
-- much
smoothly
--
getNextMsgID(
str_noUnread()
--
"Subject" =
"ScrollBar" =
-- update the status
updateMessages
4LONG s_MsgCount,s_MsgNum
-- initialize
flist
messages
initMessageList str_problemRep()
there
)least one
z > 0
--
invalid reset
= 0
-- parse
current
parseMsgText
--
browsing buttons
enabled
" = FALSE
" = TRUE
t" =
t" =
B"delete" =
--
are no
fields
"msgnum" = str_noMessages()
"address"
"department"
"office"
"phone"
"description"
"timestamp"
--
t" =
-- generate a
than contain
filter
their subjects
4s_MsgHandles
4s_MAPIerror
ZlastID
ZmsgSub
getFirstMsgID(
more
--
= getMsgSub(
--
--
getNextMsgID(
-- take
fill
appropriate
4s_MAPIError
ZmsgTxt
ender
getCurrentMsgName()
k&str_update()
fstr_OK()
str_cancel()
= getCurrentMsgText()
&&str_of()&&
= getCurrentMsgDate()
returns
getMsgName(
getMsgText(
getMsgDate(
initLinks
3SessionLogon
isMAPIAvailable
str_noMAPI
enterApplication
unlinkDLLs
s_SessionHandle
USessionLogoff
unlinkMAPI
leaveApplication
reader
FALSE
ma_GetWinIniVar
clinkMAPI
IsMAPIAvailable
freeWinPointer
$bgetWinPointer
MAPILogon
s_SessionHandle
str_OK
DgetMAPIErrorString
s_MAPIError
SessionLogOn
s_SessionHandle
str_OK
MAPILogoff
DGetMAPIErrorString
s_MAPIError
SessionLogOff
.'+ +F
$bgetWinPointer
msgID
s_SessionHandle
MAPIFindNext
d3str_lostMAPI
DgetMAPIerrorString
s_MAPIerror
getFirstMsgID
.'+ +F
$bgetWinPointer
s_SessionHandle
lpMsgSeedID
MAPIFindNext
d3str_lostMAPI
DgetMAPIerrorString
s_MAPIerror
lpMsgID
getNextMsgID
.'+ +F
freeWinPointer
$bgetWinPointer
s_SessionHandle
8aMAPIFreeBuffer
d3str_lostMAPI
DgetMAPIErrorString
s_MAPIerror
MAPIReadMail
getMsgName
.'+ +F
freeWinPointer
$bgetWinPointer
s_SessionHandle
8aMAPIFreeBuffer
d3str_lostMAPI
DgetMAPIErrorString
s_MAPIerror
MAPIReadMail
getMsgSub
.'+ +F
freeWinPointer
$bgetWinPointer
s_SessionHandle
8aMAPIFreeBuffer
y/mm/dd
d3str_lostMAPI
DgetMAPIErrorString
s_MAPIerror
h24:min
MAPIReadMail
getMsgDate
.'+ +F
freeWinPointer
$bgetWinPointer
s_SessionHandle
8aMAPIFreeBuffer
d3str_lostMAPI
DgetMAPIErrorString
s_MAPIerror
msgText
MAPIReadMail
getMsgText
.'+ +F
,&H.&
freeWinPointer
$bgetWinPointer
s_SessionHandle
recName
8aMAPIFreeBuffer
MAPIAddress
d3str_lostMAPI
DgetMAPIErrorString
s_MAPIError
getAddress
.'+ +F
,&H.&
freeWinPointer
$bgetWinPointer
s_SessionHandle
8aMAPIFreeBuffer
MAPIResolveName
d3str_lostMAPI
DgetMAPIerrorString
s_MAPIError
checkNames
.'+ +F
freeWinPointer
$bgetWinPointer
s_Sessionhandle
str_OK
d3str_lostMAPI
DgetMAPIErrorString
s_MAPIError
MAPISendMail
composeMessage
.'+ +F
s_Sessionhandle
MAPISendDocuments
str_OK
HshortFileName
d3str_lostMAPI
DgetMAPIErrorString
s_MAPIError
sendFile
.'+ +F
freeWinPointer
$bgetWinPointer
ma_hmemcpy
s_Sessionhandle
str_OK
8aMAPIFreeBuffer
MAPISendMail
MAPIResolveName
d3str_lostMAPI
DgetMAPIerrorString
s_MAPIError
recipient
sendMessage
.'+ +F
[MAPIDEleteMail
s_SessionHandle
str_OK
d3str_lostMAPI
DgetMAPIerrorString
s_MAPIError
deleteMessage
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
.', "
Too Many Sessions
Too Many Files
Invalid Message
Block Too Small
Too Many Recipients
Failure Opening Attachment
Invalid Session
Attacment Not Found
Failure Writing Attachment
Bad Recipient Type
Type Not Supported
Insufficient Memory
No Messages
Disk Full
Login Failed
Operation Succeded
Text is Too Large
Unknown Recipient
User Aborted
Operation Failed
Unknown error:
Ambiguous Recipient
getMAPIErrorString
shortFileName
&ma_globalLock
str_noMem
Kma_globalAlloc
getWinPointer
retValue
!pma_Globalhandle
Memory error occured. Operation Aborted.
ma_GlobalUnLock
} ma_GlobalFree
freeWinPointer
mapi.dll
MAPILogoff
MAPILogon
MAPIFindNext
MAPIFreeBuffer
MAPISendMail
MAPIReadMail
,CUy er.'
MAPIResolveName
,CU_Glo.'
MAPISendDocuments
MAPIAddress
MAPIDeleteMail
linkMAPI
getWinIniVar
ma_getWinIniVar
globalAlloc
ma_globalAlloc
globalLock
ma_globalLock
,$U=
globalUnlock
ma_globalUnlock
,$T?Hpg-#
globalFree
ma_globalFree
globalHandle
ma_globalHandle
,#U_=
hmemcpy
ma_hmemcpy
tb40win.dll
kernel
initLinks
mapi.dll
unlinkMAPI
tb40win.dll
kernel
unlinkDLLs
You have no unread messages.
str_noUnread
You have
messages.
str_msgCountAll
unread messages.
You have
str_msgCountUnread
MAPI is not available at this time.
You need to have Microsoft Mail or MAPI-compatible e-mail client software installed
for the examples in this book to function correctly.
str_noMAPI
The examples in this book will not function correctly,
MAPI is not available at this time.
you may wish to exit.
str_lostMAPI
str_OK
These names could not be resolved:
str_notResolved
Message sent.
str_sent
Message not sent:
str_notSent
Report not submitted:
str_notSubmit
Report submitted.
str_submit
Message not deleted:
str_notDelete
No messages
str_noMessages
Error:
str_error
Update Messages?
str_update
Cancel
str_cancel
Message
str_message
str_of
Problem Report
str_problemRep
Aborting operation: Memory Allocation Error.
str_noMem
.'+ +F
.&, 7
.'+ +F
(str_noUnread
l'getNextMsgID
ScrollBar
getMsgSub
1RgetFirstMsgID
Subject
getMsgName
buttonClick
uupdateMessages
enterPage
+&,""
+&,">
+&,""
.'+&?
problem
s_MsgNum
phone
address
description
str_noMessages
previous
delete
8parseMsgText
initMessageList
msgnum
office
department
timestamp
str_problemRep
s_MsgCount
updateMessages
.'+ +F
.'+&?
+&,"Y
+&,I3
.'+ +F
FALSE
l'getNextMsgID
getMsgSub
s_MsgHandles
1RgetFirstMsgID
s_MsgCount
initMessageList
w, #>
+&, #?
w, #?
+&, #?
address
s_MAPIError
phone
str_cancel
description
'getCurrentMsgText
str_message
getCurrentMsgDate
problem
uupdateMessages
str_OK
getCurrentMsgName
msgnum
str_update
str_of
s_MsgNum
Error:
office
department
timestamp
s_MsgCount
parseMsgText
+&,I3
s_MsgNum
s_MsgHandles
getMsgName
getCurrentMsgName
+&,I3
getMsgText
s_MsgNum
s_MsgHandles
getCurrentMsgText
+&,I3
s_MsgNum
s_MsgHandles
getMsgDate
getCurrentMsgDate
str_submit
str_notDele
examples
in,true
ThreeDeeRect
text area
bottomLine
topLine
description
description
enterpage
doesn't fit,
notifybefore
"description"
Front
front
enterpage
handler keeps the title
synchronized
notifybefore
"front"
buttonClick
enterPage
buttonClick
-- determine
navigation
should be allowed
notifybefore
on a different
oenabled = (
Previous
buttonClick
enterPage
.one
buttonClick
-- determine
navigation
should be allowed
notifybefore
on a different
oenabled = (
main menu
buttonClick
main menu
enterPage
the main
buttonClick
-- determine
Bnavigation
Ienu
should be allowed:
notifybefore
ycurrent
oenabled = (
in,true
ThreeDeeRect
work area
bottomLine
topLine
enterPage
main menu
-- a notify handler was used
update
you enter
Main Menu
Main Menu
buttonClick
,&H.&
front
enterpage
buttonClick
ZLONG lineNum
-- determine which
Uwas selected
* = selectedTextlines
that
-- update the
list
notifybefore
ZSTRING newText
-- generate a
-- optimization:
faster
aincremental
place
, than
-- directly
B(i-1)
J"front"
Using MAPI
Linking to MAPI.DLL
Looking up Addresses
Verifying Names
Checking For Unread Mail
Counting Messages
Composing Mail
Sending Messages
Example: Problem Reports
Choose one of these topics:low by clicking on its name:
enterpage
Example: Problem Reports
Example: Problem Reports
Example: Problem Reports+
The following two examples demonstrate how a small MAPI application, such as a custom e-mail form, might be built in ToolBook.
The first example is a guided input form for submitting problem reports. The user simply fills in the blanks and clicks on a button to submit the report.
The second example scans the user's incoming mail folder for problem reports submitted using the e-mail form. This provides a simple interface for browsing through these messages...................................
Submit Reports
examples
Submit Reports
buttonClick
buttonClick
-- display a
example
"examples"
currentpage
"Submit Reports"
&Submit Reports
Receive Reports
Receive Reports
examples
buttonClick
buttonClick
-- display a
example
"examples"
currentpage
"Receive Reports"
&Receive Reports
main menu
right
grey all
grey left
grey right
Looking up Addresses
-- a notify handler was used
the address
you enter
Looking up Addressesok]
Looking up Addressesokkess Book
Click Look Up Address to display the dialog box MAPI provides for choosing addresses. Names you select from the list will be placed in the field below...........................